+2002-01-11 Havoc Pennington <hp@pobox.com>
+
+ * gtk/gtklabel.c: put in more links to Pango markup format docs
+ (gtk_label_set_justify): mention gtk_misc_set_alignment
+
2002-01-12 Tor Lillqvist <tml@iki.fi>
Fixes contributed by Archaeopteryx Software: This is a first small
+2002-01-11 Havoc Pennington <hp@pobox.com>
+
+ * gtk/gtklabel.c: put in more links to Pango markup format docs
+ (gtk_label_set_justify): mention gtk_misc_set_alignment
+
2002-01-12 Tor Lillqvist <tml@iki.fi>
Fixes contributed by Archaeopteryx Software: This is a first small
+2002-01-11 Havoc Pennington <hp@pobox.com>
+
+ * gtk/gtklabel.c: put in more links to Pango markup format docs
+ (gtk_label_set_justify): mention gtk_misc_set_alignment
+
2002-01-12 Tor Lillqvist <tml@iki.fi>
Fixes contributed by Archaeopteryx Software: This is a first small
+2002-01-11 Havoc Pennington <hp@pobox.com>
+
+ * gtk/gtklabel.c: put in more links to Pango markup format docs
+ (gtk_label_set_justify): mention gtk_misc_set_alignment
+
2002-01-12 Tor Lillqvist <tml@iki.fi>
Fixes contributed by Archaeopteryx Software: This is a first small
+2002-01-11 Havoc Pennington <hp@pobox.com>
+
+ * gtk/gtklabel.c: put in more links to Pango markup format docs
+ (gtk_label_set_justify): mention gtk_misc_set_alignment
+
2002-01-12 Tor Lillqvist <tml@iki.fi>
Fixes contributed by Archaeopteryx Software: This is a first small
+2002-01-11 Havoc Pennington <hp@pobox.com>
+
+ * gtk/gtklabel.c: put in more links to Pango markup format docs
+ (gtk_label_set_justify): mention gtk_misc_set_alignment
+
2002-01-12 Tor Lillqvist <tml@iki.fi>
Fixes contributed by Archaeopteryx Software: This is a first small
+2002-01-11 Havoc Pennington <hp@pobox.com>
+
+ * gtk/gtklabel.c: put in more links to Pango markup format docs
+ (gtk_label_set_justify): mention gtk_misc_set_alignment
+
2002-01-12 Tor Lillqvist <tml@iki.fi>
Fixes contributed by Archaeopteryx Software: This is a first small
+2002-01-11 Havoc Pennington <hp@pobox.com>
+
+ * gtk/running.sgml: sgml fixes
+
+ * gtk/tmpl/gtksignal.sgml: sgml fixes
+
+ * gtk/tmpl/gtklabel.sgml: do the intro section
+
2002-01-09 Matthias Clasen <matthiasc@poet.de>
* gtk/tmpl/gtkaccellabel.sgml: Remove duplicate docs.
<para>
All GTK+ applications support a number of standard commandline
-options. These are removed from <literal>argv</literal> by
-gtk_init(). Modules may parse and remove further options.
+options. These are removed from <literal>argv</literal> by <link
+linkend="gtk-init">gtk_init()</link>. Modules may parse and remove
+further options.
</para>
<formalpara>
<title><systemitem>--g-fatal-warnings</systemitem></title>
<para>
-Make GTK+ abort on all warnings.
+Make GTK+ abort on all warnings. This is useful to stop on the first
+warning in a debugger, if your application is printing multiple
+warnings. It's almost always best to start debugging with the first
+warning that occurs.
</para>
</formalpara>
<listitem><para>Visual feedback about window updates</para></listitem>
</varlistentry>
</variablelist>
- The special value <term>all</term> can be used to turn on all debug options.
+ The special value <literal>all</literal> can be used to turn on all debug options.
</para>
</formalpara>
(If <envar>GTK_EXE_PREFIX</envar> is defined, <libdir> is
<filename>$GTK_EXE_PREFIX/lib</filename>. Otherwise it is the libdir
specified when GTK+ was configured, usually
- <filename>/usr/local/lib</libdir>.)
+ <filename>/usr/local/lib</filename>.)
For each directory in the list, GTK+ actually looks first in
a subdirectory named after the version number of GTK+, then in the
directory itself and finally in the system-specific library path.
the RC files, which in turn overwrites the default value
<filename><sysconfdir>/gtk-2.0/gtk.immodules</filename>
(<sysconfdir> is the sysconfdir specified when GTK+ was configured,
- usually <filename>/usr/local/etc</libdir>.)
+ usually <filename>/usr/local/etc</filename>.)
</para>
-<formalpara>
+</formalpara>
<formalpara>
<title><envar>GTK_RC_FILES</envar></title>
<para>
Specifies a list of RC files to parse instead of the default ones;
see <link linkend="gtk-Resource-Files">Resource Files</link>.
+ </para>
</formalpara>
<formalpara>
<title><envar>GTK_DATA_PREFIX</envar></title>
<para>
- If set, makes GTK+ use <filename>$GTK_DATA_PREFIX<filename>
+ If set, makes GTK+ use <filename>$GTK_DATA_PREFIX</filename>
instead of the prefix configured when GTK+ was compiled.
</para>
</formalpara>
<listitem><para>Information about XIM support</para></listitem>
</varlistentry>
</variablelist>
- The special value <term>all</term> can be used to turn on all debug options.
+ The special value <literal>all</literal> can be used to turn on all debug options.
</para>
</formalpara>
@child1_req:
@child2_req:
-<!-- ##### MACRO gtk_paned_handle_size ##### -->
-<para>
-Old name for gtk_paned_set_handle_size().
-</para>
-
-
<!-- ##### FUNCTION gtk_paned_set_handle_size ##### -->
<para>
Set the the handle size to @size x @size pixels.
</para>
@accel_label:
-@accel_widget:
+@accel_widget:
<!-- ##### FUNCTION gtk_accel_label_get_accel_width ##### -->
<!-- ##### SECTION Long_Description ##### -->
<para>
-The #GtkLabel widget is usually used directly by the programmer to display
-word(s) describing an adjacent widget or its use. It is also used internally
-by Gtk+ as #GtkButton labels, #GtkMenu items, and many other widgets which
-use text.
+The #GtkLabel widget displays a small amount of text. As the name
+implies, most labels are used to label another widget such as a
+#GtkButton, a #GtkMenuItem, or a #GtkOptionMenu.
+</para>
+
+<refsect2>
+<title>Mnemonics</title>
+
+<para>
+Labels may contain <firstterm>mnemonics</firstterm>. Mnemonics are
+underlined characters in the label, used for keyboard navigation.
+Mnemonics are created by providing a string with an underscore before
+the mnemonic character, such as <literal>"_File"</literal>, to the
+functions gtk_label_new_with_mnemonic() or
+gtk_label_set_text_with_mnemonic().
+</para>
+
+<para>
+Mnemonics automatically activate any activatable widget the label is
+inside, such as a #GtkButton; if the label is not inside the
+mnemonic's target widget, you have to tell the label about the target
+using gtk_label_set_mnemonic_widget(). Here's a simple example where
+the label is inside a button:
+
+<informalexample>
+<programlisting>
+ /* Pressing Alt+H will activate this button */
+ button = gtk_button_new ();
+ label = gtk_label_new_with_mnemonic ("_Hello");
+ gtk_container_add (GTK_CONTAINER (button), label);
+</programlisting>
+</informalexample>
+There's a convenience function to create buttons with a mnemonic label
+already inside:
+
+<informalexample>
+<programlisting>
+ /* Pressing Alt+H will activate this button */
+ button = gtk_button_new_with_mnemonic ("_Hello");
+</programlisting>
+</informalexample>
+
+To create a mnemonic for a widget alongside the label, such as a
+#GtkEntry, you have to point the label at the entry with
+gtk_label_set_mnemonic_widget():
+<informalexample>
+<programlisting>
+ /* Pressing Alt+H will focus the entry */
+ entry = gtk_entry_new ();
+ label = gtk_label_new_with_mnemonic ("_Hello");
+ gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);
+</programlisting>
+</informalexample>
+
+</para>
+
+</refsect2>
+
+<refsect2>
+<title>Markup (styled text)</title>
+
+<para>
+To make it easy to format text in a label (changing colors, fonts,
+etc.), label text can be provided in a simple <link
+linkend="PangoMarkupFormat">markup format</link>.
+Here's how to create a label with a small font:
+<informalexample>
+<programlisting>
+ label = gtk_label_new (NULL);
+ gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>");
+</programlisting>
+</informalexample>
+(See <link
+linkend="PangoMarkupFormat">complete documentation</link> of available
+tags in the Pango manual.)
+</para>
+<para>
+The markup passed to gtk_label_set_markup() must be valid; for
+example, literal </>/& characters must be escaped as
+&lt;, &gt;, and &amp;. If you pass text obtained from
+the user, file, or a network to gtk_label_set_markup(),
+you'll want to escape it with g_markup_escape_text().
</para>
+<para>
+Markup strings are just a convenient way to set the #PangoAttrList on
+a label; gtk_label_set_attributes() may be a simpler way to set
+attributes in some cases. Be careful though; #PangoAttrList tends to
+cause internationalization problems, unless you're applying attributes
+to the entire string (i.e. unless you set the range of each attribute
+to [0, G_MAXINT)). The reason is that specifying the start_index and
+end_index for a #PangoAttribute requires knowledge of the exact string
+being displayed, so translations will cause problems.
+</para>
+</refsect2>
+
+<refsect2>
+<title>Selectable labels</title>
+
+<para>
+Labels can be made selectable with gtk_label_set_selectable().
+Selectable labels allow the user to copy the label contents to
+the clipboard. Only labels that contain useful-to-copy information
+— such as error messages — should be made selectable.
+</para>
+</refsect2>
+
+<refsect2>
+<title>Text layout</title>
+
+<para>
+A label can contain any number of paragraphs, but will have
+performance problems if it contains more than a small number.
+Paragraphs are separated by newlines or other paragraph separators
+understood by Pango.
+</para>
+<para>
+Labels can automatically wrap text if you call
+gtk_label_set_line_wrap().
+</para>
+<para>
+gtk_label_set_justify() sets how the lines in a label align
+with one another. If you want to set how the label as a whole
+aligns in its available space, see gtk_misc_set_alignment().
+</para>
+
+</refsect2>
<!-- ##### SECTION See_Also ##### -->
<para>
@child: the child to add
+<!-- ##### MACRO gtk_paned_handle_size ##### -->
+<para>
+Old name for gtk_paned_set_handle_size().
+</para>
+
+
+
<!-- ##### MACRO gtk_paned_gutter_size ##### -->
<para>
Old name for gtk_paned_set_gutter_size().
<!-- ##### SECTION Long_Description ##### -->
<para>
The GTK+ signal system merely proxies the GLib signal system now. For future
-usage, direct use of the <link linkend="gobject-Signals">GSignal</linkend> API is recommended, this avoids significant
+usage, direct use of the <link linkend="gobject-Signals">GSignal</link> API is recommended, this avoids significant
performance hits where #GtkArg structures have to be converted into #GValue<!>s.
</para>
@GTK_COMPOSITE_CHILD:
Indicates that the widget is a composite child of its parent; see
gtk_widget_push_composite_child(), gtk_widget_pop_composite_child().
-@GTK_NO_REPARENT:
- Unused since before GTK+ 1.2, will be removed in a future version.
+@GTK_NO_REPARENT:
+ Unused since before GTK+ 1.2, will be removed in a future version.
@GTK_APP_PAINTABLE:
Set and unset by gtk_widget_set_app_paintable().
Must be set on widgets whose window the application directly draws on,
* @label: a #GtkLabel
* @str: a markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>)
*
- * Parses @str which is marked up with the Pango text markup language,
+ * Parses @str which is marked up with the <link linkend="PangoMarkupFormat">Pango text markup language</link>,
* setting the label's text and attribute list based on the parse results.
**/
void
* @label: a #GtkLabel
* @str: a markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>)
*
- * Parses @str which is marked up with the Pango text markup language,
+ * Parses @str which is marked up with the <link linkend="PangoMarkupFormat">Pango text markup language</link>,
* setting the label's text and attribute list based on the parse results.
* If characters in @str are preceded by an underscore, they are underlined
* indicating that they represent a keyboard accelerator called a mnemonic.
*
* Sets the alignment of the lines in the text of the label relative to
* each other. %GTK_JUSTIFY_LEFT is the default value when the
- * widget is first created with gtk_label_new().
+ * widget is first created with gtk_label_new(). If you instead want
+ * to set the alignment of the label as a whole, use
+ * gtk_misc_set_alignment() instead. gtk_label_set_justify() has no
+ * effect on labels containing only a single line.
**/
void
gtk_label_set_justify (GtkLabel *label,
* @label: a #GtkLabel
* @setting: %TRUE if the label's text should be parsed for markup.
*
- * Sets whether the text of the label contains markup in Pango's
- * text markup lango. See gtk_label_set_markup().
+ * Sets whether the text of the label contains markup in <link
+ * linkend="PangoMarkupFormat">Pango's text markup
+ * language</link>. See gtk_label_set_markup().
**/
void
gtk_label_set_use_markup (GtkLabel *label,
* gtk_label_get_use_markup:
* @label: a #GtkLabel
*
- * Returns whether the label's text is interpreted as marked up with the
- * Pango text markup language. See gtk_label_set_use_markup ().
+ * Returns whether the label's text is interpreted as marked up with
+ * the <link linkend="PangoMarkupFormat">Pango text markup
+ * language</link>. See gtk_label_set_use_markup ().
*
* Return value: %TRUE if the label's text will be parsed for markup.
**/
projects / gtk4.git / commitdiff